Xeoma и системы умный дом

Интеграция с системами умный дом

Для такой интеграции настоятельно рекомендуем использовать утилиту curl. Она входит по умолчанию во многие дистрибутивы Linux и MacOS; пользователям Windows нужно скачать её вручную.

В последние годы многие прониклись желанием автоматизировать различные повседневные процессы, ведь современные технологии позволяют нам добиваться максимального удобства. Именно к этому и стремятся системы умный дом, которые укрепляют связь между таким удобством и безопасностью; особо заметный вклад в эту сферу вносит IoT.
В этой статье мы поговорим о нескольких системах умный дом и о том, как можно «подружить» их с Xeoma, чтобы получить более полную автоматизацию.

Прежде чем с головой погрузиться в тему, мы предлагаем вам окунуться в небольшой словарь терминов, которые вы встретите в статье; здесь они снабжены краткими пояснениями, которые актуальны для нашего контекста.

Словарь ☟

API (англ. Application Programming Interface) – набор команд, которыми устройства могут общаться друг с другом, а также правила их применения.
IoT (англ. Internet of Things) – интернет вещей, сочетание различных устройств, которые общаются друг с другом посредством Интернета.
JSON (англ. JavaScript Object Notation) – простой язык, который часто используется для общения по HTTP между приложениями/устройствами.
Заголовок (англ. header) – часть HTTP-запроса, у которой есть имя и значение (обычно они записываются так: «имя-заголовка: значение-заголовка»); один запрос может содержать несколько заголовков; они помогают получателю понять содержимое и суть запроса.
Параметр и значение – простое сочетание какой-либо функции и её состояния; обычно пишутся так: "lock"="opened" – здесь параметру «lock» (замок) присваивается значение «opened» (открыт).
Токен (англ. token) – беспорядочный набор символов, который показывает системе, что его предъявитель имеет право отправлять такой HTTP-запрос; можно считать его удостоверением личности.

Многие устройства Samsung поддерживают SmartThings API – с его помощью можно их контролировать, используя JSON. Допустим, что нам нужно добавлять яркость к лампе над входом, когда к нему подходит человек:

Проще всего перечислять все JSON-параметры и значения в отдельном текстовом файле, например, data.json. Вот пример содержимого такого файла для задачи со светом:
{"commands":[{"component":"main","capability":"switchLevel","command": "setLevel","arguments":[90]}]}
Здесь самая важная часть – 90, это яркость по шкале от 0 до 100.

Модулю Запуск приложения надо указать название утилиты и список параметров для неё. Утилитой здесь будет выступать curl (на Windows нужно указать полный путь до неё, если, конечно, вы заблаговременно не поигрались с переменными среды).
Вот набор нужных параметров для неё:
-d @"/home/user1/data.json" -H "Authorization: token_goes_here" -H "Content-Type: application/json" -X POST https://api.smartthings.com/v1/devices/6f5eс124-4c02-baac-a222-cc129c1880c3/commands

Краткое описание того, как curl их воспринимает: ☟

-d – после этого идёт содержимое запроса;
@ – использовать содержимое файла, а не сам файл;
-H – использовать этот заголовок;
-X – отправить запрос такого типа;
6f5…0c3 – уникальный идентификатор устройства (в нашем случае это лампа).

Допустим, мы хотим включать сигнал тревоги, когда в кадре появляется лицо, не входящее в список доверенных:

Убеждаемся, что Распознавание лиц работает в режиме Реагировать на неизвестных и невыбранных людей. Настройки Запуска приложения останутся примерно теми же (изменим только идентификатор устройства), но появится новая информация в .json-файле:
{"commands":[{"component":"main","capability":"alarm","command":"siren"}]}

Отслеживать состояние большинства IoT устройств, а также управлять ими, можно удалённо. Здесь стоит обратить внимание на Smappee API – его основная цель заключается в контроле за потреблением электроэнергии, воды, газа и т.д. Допустим, мы хотим немедленно отключить подачу энергии/газа к плите, если камера заметила дым и/или огонь поблизости от неё. Это можно сделать так:

Утилитой для Запуска приложения вновь будет curl. Его параметры:
-d @"/home/user1/data.json" -H "Authorization: Bearer token_goes_here" -H "Content-Type: application/json" -X POST https://app1pub.smappee.net/dev/v1/servicelocation/113355/actuator/2/off
В этот раз содержимое .json-файла скромнее:
{"duration":0}
Здесь 0 означает, что устройство останется выключенным, пока не получит отдельную команду на включение, а не включиться обратно самостоятельно после X секунд.

С помощью этого же API можно работать с гаражными воротами, например, если мы хотим открывать их автоматически, когда камера увидела верный номерной знак рядом с ними:

Убеждаемся, что Распознавание номеров работает в режиме Пропускать при появлении номера из белого списка. Параметры для curl:
-d @"/home/user1/data.json" -H "Authorization: Bearer token_goes_here" -H "Content-Type: application/json" -X PATCH https://app1pub.smappee.net/dev/v3/servicelocation/224466/smartdevices/MyGarageDoor
(обратите внимание, что здесь другой тип запроса: PATCH, а не POST)

Содержимое .json-файла:
{"configurationProperties":[{"value":{"unit":"None","value": "Opened"},"spec":{"name":"etc.smart.device.type.door.state"}}]}

Ещё одну возможность интегрироваться с системами умный дом нам даёт Wink API – он поддерживает много брендов сигнализаций, камер, дверных звонков и т.д. Живёте один и хотите, чтобы входная дверь всегда была закрыта, даже если, уходя, вы забыли о ней? Можно возложить эти обязанности на камеру, которая смотрит на дверь снаружи:

Убеждаемся, что Распознавание лиц работает в режиме Реагировать только на выбранных людей. Утилитой для Запуска приложения будет curl. Её параметры:
-d @"/home/user1/data.json" -H "Authorization: Bearer token_goes_here" -H "Content-Type: application/json" -X PUT https://api.wink.com/lock/11810/desired_state
(обратите внимание, что здесь другой тип запроса: PUT, а не POST)

Содержимое .json-файла:
{"desired_state":{"locked":true}}

Хотите, чтобы шторы раздвигались автоматически на рассвете и задвигались на закате? Этим тоже может заниматься внешняя камера:

Модули Отправка HTTP команд контролируют работу HTTP Переключателей: один включается по началу события (рассвет), другой – по окончанию события (закат).
В Запусках приложений параметры будут одинаковые:
-d @"/home/user1/filename.json" -H "Authorization: Bearer token_goes_here" -H "Content-Type: application/json" -X PUT https://api.wink.com/blind/23214/desired_state
Содержимое .json-файла будет немного отличаться:
открываем:
{"desired_state":{"position":1.0}}
закрываем:
{"desired_state":{"position":0.0}}

Во всех предыдущих примерах мы рассматривали сценарий, когда Xeoma отправляет команды на внешние устройства, ориентируясь на показания своих детекторов. В этот раз пускай внешнее IoT устройство передаст Xeoma нужные данные. Начать можно с метеокомплекса – так Xeoma сможет наложить информацию прямо на картинку с камеры. Для этих целей прекрасно подходит Netatmo Connect API – он предоставит нам всю информацию об окружающей обстановке по всего одному запросу.
Наложением текста на видео займётся HTTP Маркировщик, но кто-то должен передать ему команды с нужными параметрами. Вот пример простого shell-скрипта (Linux), который запрашивает данные у Netatmo и передаёт их в Xeoma: https://felenasoft.com/xeoma/downloads/other/smarthome_sample.sh

Так это будет выглядеть в Xeoma:

Такой скрипт можно запускать с любой частотой, чтобы данные были актуальны – получая новую команду с теми же параметрами, но новыми значениями для них, HTTP Маркировщик просто обновляет значения.

Отдельно стоит отметить, что различных голосовых помощников (например, Google Assistant или Яндекс Алису) можно «научить» отправлять конкретный HTTP-запрос по голосовой команде – это хорошо работает с модулем HTTP Переключатель, т.к. он позволяет легко включать и выключать любые модули.

Эта статья, конечно, не является полным перечнем API; системы умный дом сейчас имеют огромное их количество. Её цель – продемонстрировать основные способы работы с такими API. Поэтому, даже если вашей любимой системы здесь нет, не огорчайтесь – скорее всего, она тоже сможет работать в паре с Xeoma, используя схожие принципы.

Выражаем благодарность ресурсу ProgrammableWeb (https://www.programmableweb.com/) за поддержание действительно полного списка API.

Документация по упомянутым в статье API:
SmartThings: https://smartthings.developer.samsung.com/docs/api-ref/st-api.html
Smappee: https://smappee.atlassian.net/wiki/spaces/DEVAPI/
Wink: https://winkapiv2.docs.apiary.io/
Netatmo Connect: https://dev.netatmo.com/apidocumentation/

4 июня 2021